home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 051-075 / disk_073 / lit / lit.man < prev    next >
Text File  |  1992-05-06  |  11KB  |  302 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                             LIT TEXT UTILITY MANUAL
  7.  
  8.                              Version 2.0, 11/19/86
  9.                       Copyright (C) 1986  Donald J. Irving
  10.  
  11.   Lit  is  a  command  line invoked text utility which filters a text file to
  12.   stdout   printing  printable  characters  as  they  are,  and  showing  all
  13.   non-printable  characters  in  any  one  or  more  of  three representation
  14.   formats.   The  only  character interpreted (acted upon) by lit is the line
  15.   feed  character which causes lit to issue a line feed.  The inspiration for
  16.   lit  came from the "l" command in many of the UNIX line editors. Lit is not
  17.   quite  the  same  as  any  of  these, however. For one thing, lit output is
  18.   never ambiguous.  
  19.  
  20.   Here is an example of what lit does: 
  21.  
  22.       Say the file 'myfile' consists of the following ascii characters: 
  23.  
  24.               HT, HT, h, e, l, l, o, space, w, o, r, l, d, BEL, LF
  25.  
  26.       Saying 'lit myfile' would produce the following output:
  27.  
  28.               \t\thello world\007\n
  29.  
  30.       And saying 'lit myfile [various options]' might produce any of:
  31.  
  32.               \t\thello world^G\n
  33.               ^I^Ihello world^G^J
  34.               \011\011hello world\007\012
  35.               \09\09hello world\07\0A
  36.               \009\009hello world\007\010
  37.  
  38.   You control the output with optional command line arguments which provide: 
  39.  
  40.       1. The name of the file to read as input.
  41.       2. What subset of the file lines to print.
  42.       3. In which format(s) to represent non-printable characters.
  43.       4. Which number base to use for numeric representations.
  44.  
  45.   If you do not supply these, they default (in the original version) to:
  46.  
  47.       1. Stdin.
  48.       2. The whole file.
  49.       3. Backslash constructs if possible else  numeric representations.
  50.       4. Octal.
  51.  
  52.   Here  is  the  command line template. The arguments may be specified in any
  53.   order.  The  -bcanohd  options may be stacked after one minus sign, or they
  54.   may appear as separate arguments.  
  55.  
  56.       lit [<filename>] [-s<linenum>] [-p<numlines>] [-[bcan][ohd]] 
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.                           THE NAME OF THE INPUT FILE
  67.  
  68.   The  first  command  line argument  encountered which does not start with a
  69.   minus  sign   is  considered  to  be  the  input  file name. Any subsequent
  70.   command  line argument which does not start with a minus sign is considered
  71.   to  be an error.  If no command line argument is found which does not start
  72.   with a minus sign lit uses <stdin> for input.  
  73.  
  74.                     PRINTING A SUBSET OF LINES OF THE FILE
  75.  
  76.   Lit  prints the whole file by default. You can tell it on which line in the
  77.   file  to  start printing and/or how many lines to print by supplying either
  78.   of both of these command line arguments: 
  79.  
  80.       -s<linenum>         lit will start printing at line <linenum>
  81.       -p<numlines>        lit will print <numlines> lines
  82.  
  83.   There  is  no  space  between  the  's'  or 'p' and the number. There is no
  84.   validity checking on the number values.  
  85.  
  86.                FORMATS FOR REPRESENTING NON-PRINTABLE CHARACTERS
  87.  
  88.   There   are   three  formats  in  which  non-printable  characters  may  be
  89.   represented:  C  Language  style  backslash  representations  such  as  \n,
  90.   control   character   representations   such   as  ^J,  and  numeric  value
  91.   representations such as \012.  
  92.  
  93.   C Language Backslash Representations 
  94.  
  95.   The  form  is a backslash followed by a lower case letter. Here is the list
  96.   of the applicable characters: 
  97.  
  98.       line feed           \n
  99.       horizontal tab      \t
  100.       backspace           \b
  101.       carriage return     \r
  102.       form feed           \f
  103.  
  104.   The  ascii  NUL character representation \0 is omitted.  NUL is represented
  105.   by its control character representation or as a numeric value.  
  106.  
  107.   Control Character Representations 
  108.  
  109.   The  form is a caret followed by another symbol, where the second symbol is
  110.   the  keyboard  control  character  of the character to be represented.  For
  111.   example,  the  ascii  line  feed character is represented as ^J.  The ascii
  112.   character DEL has an arbitrarily assigned representation of ^?.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.   ASCII Numeric Value Representations 
  127.  
  128.   The  representation  is  in  the  form  \num  where  num is the character's
  129.   numeric  value. (the unsigned integer value of its eight bits) displayed in
  130.   any  of  the  three number bases octal, decimal, or hexadecimal.  For octal
  131.   representations,   num   is   exactly   three   octal   digits;   for   hex
  132.   representations,  num  is  exactly two hexadecimal digits; and for  decimal
  133.   representations,  num  is  exactly three decimal digits. Num is zero-padded
  134.   on  the  left  if  necessary to make up the required number of digits.  For
  135.   example,  the  ESC  char  is  represented  as  \033, \027, or \1B in octal,
  136.   decimal,  and  hex  respectively.  NUL  would  be \000, \000, or \00.  This
  137.   format  is  not  limited  to  ascii  characters;  any  eight  bits  can  be
  138.   represented.  Numbers  of  \200  (octal),  \128  (decimal),  \80  (hex), or
  139.   greater  are  byte  values beyond the upper end of the ascii character set.
  140.   The  largest  byte value (all bits on) is  \377 (octal), \255 (decimal), or
  141.   \FF (hex).  
  142.  
  143.           COMMAND LINE ARGUMENTS FOR SELECTING REPRESENTATION FORMATS
  144.  
  145.   You  tell  lit which representation format or combination of formats to use
  146.   for   non-printable  characters  by  supplying  one  of  the  command  line
  147.   arguments  -b,  -c,  -a,  or  -n.  If  you supply none of these, then -b is
  148.   selected  by  default.   If  you  supply  more  than  one,  then the latter
  149.   supersedes the former.  
  150.  
  151.       -b      use backslash representations such as \n
  152.               if possible, else use numeric representations.
  153.  
  154.       -c      use control char representations such as ^J
  155.               if possible, else use numeric representations.
  156.  
  157.       -a      all; use backslash reps if possible, else use control
  158.               char reps if possible, else use numeric representations.
  159.  
  160.       -n      use numeric representations only.
  161.  
  162.  
  163.   You  tell  lit  which  number  base  to  use for numeric representations by
  164.   providing  one  of  the command line arguments -o, -h, or -d. If you supply
  165.   none  of  these,  then  -o is selected by default.  If you supply more than
  166.   one, then the latter supersedes the former.  
  167.  
  168.       -o      octal
  169.       -h      hexadecimal
  170.       -d      decimal
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.                             EXCEPTIONAL CHARACTERS
  187.  
  188.   Two  characters have special meaning in lit output. The backslash character
  189.   \  always  has  special  meaning. The caret character ^ has special meaning
  190.   whenever control character representations are enabled.  
  191.  
  192.   The Backslash Character \ 
  193.  
  194.   As  already  described, the \ character in lit output signals the beginning
  195.   of  either  a  special  letter  representation  such  as  \n  or  a numeric
  196.   representation  such  as \012. The \ is also used to relieve a subsequent \
  197.   or  ^  of  its  special meaning.  \\ represents the actual character \, and
  198.   (when  control  character  representations  are  enabled) \^ represents the
  199.   actual character ^.  
  200.  
  201.   The Caret Character ^ 
  202.  
  203.   When  control  character  representations  are  enabled,  a  ^  signals the
  204.   beginning  of  a  control  character  representation  such  as ^J. Note the
  205.   implication  therefore that ^^ means Control caret (ascii RS), and ^\ means
  206.   Control  backslash  (ascii FS). In both of these cases the second character
  207.   is  relieved  of  its  special  meaning  because  it is part of the control
  208.   character  representation.   If  control  character representations are not
  209.   enabled, then ^ is just another printable character.  
  210.  
  211.                                   CONCLUSION
  212.  
  213.   Lit  fills  the  gap  between  text editors which usually interpret special
  214.   characters  in  special  ways,  and  hex dump utilities which make terrible
  215.   reading  for  text  files.   One  of  lit's  greatest  strengths is that it
  216.   interprets  nothing  but  the  linefeed  character; everything else is just
  217.   represented to the output stream.  
  218.  
  219.   Although  lit  provides  a  variety  of  output  formats,  perhaps its main
  220.   usefulness  is in quickly locating U.F.O.s (Unidentified File Objects) that
  221.   have  gotten into your text files.  (like that ESC char that's wierding out
  222.   your  printer) For this purpose, the default options are adequate, and, for
  223.   C programmers at least, already familiar.  
  224.  
  225.  
  226.  
  227.   Donald J. Irving
  228.   9812 Gardenwood Way
  229.   Sacramento, CA 95827
  230.   (916) 366-3225
  231.  
  232.   CIS:    73547,1335
  233.   PLINK:  ops158
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.   Post scripts:  
  247.  
  248.   ** 
  249.  
  250.   One  convenient way of getting to know lit is to use the default input file
  251.   stdin.  Just  say  'lit [-options]' with no file name. Now you  can type in
  252.   lines  one  at  a  time  and  have lit filter them back to you.  Try typing
  253.   control  characters  to  see how they come back.  Keep in mind that in this
  254.   configuration,  the  CLI  is  still trapping and interpreting (acting upon)
  255.   what  you type, so  screen control characters like  form feed, and tab, for
  256.   example,  actually  cause form feeds and tabs to occur on the screen before
  257.   lit  has  a chance to send you its output.  This may make the screen look a
  258.   little  messy,  but  at  least if the CLI is interpreting everything it can
  259.   tell when you type Control C to break out.  
  260.  
  261.   ** 
  262.  
  263.   Want  to  have  lit  give  you a Usage statement? Say 'lit lskdmlsdm' where
  264.   lskdmlsdm  is  any  string of garbage which doesn't add up to the name of a
  265.   real file.  
  266.  
  267.   ** 
  268.  
  269.   Why  not  use  \0  to  represent  NUL?  Consider  the  following  character
  270.   sequence: 
  271.  
  272.               BEL, space, NUL, 0, 7 
  273.  
  274.   Using  \0  for  NUL  would  yield  the  output  '\007  \007'. To avoid this
  275.   ambiguity,   the   \0   construct   is   not   included  in  the  backslash
  276.   representations.  
  277.  
  278.   ** 
  279.  
  280.   Why  use  ^?  for  DEL?  Keyboard  control  characters are always 64 places
  281.   higher   in   the  ascii  table  than  the  non-printable  characters  they
  282.   represent.   DEL is at the high end of the ascii character set, however, so
  283.   there's  no  keyboard  character  to  represent it.  We need to arbitrarily
  284.   choose  some  character.   The  ?  seems  to  make at least some sense as a
  285.   choice;  it  is  64  places  less than DEL, and that kind of satisfies ones
  286.   desire  for  symmetry  in the world. (Besides, some of the UNIX world tools
  287.   already do it that way.) 
  288.  
  289.   **
  290.  
  291.   If  you  don't  like  the  default option settings, they are very simple to
  292.   change  in  the  C  source.  If you don't have a C compiler, and can't live
  293.   with  the  settings,  I  will  be willing to recompile it with your desired
  294.   option  settings.  Send me a disk in a protective mailer and include return
  295.   postage. I will return your disk in the same mailer.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.